PlantUML Hitchhiker

Standardising Standard Library

Plantuml Stdlib Terminology

Term Meaning
PlantUML Stdlib Plantuml Standard Library
i.e. https://github.com/plantuml/plantuml-stdlib
Library Plantuml stdlib consists of several icon libraries
e.g. awslib, elastic, azure…
Category Each icon library consists one or more icons categories
Category is a subdir / grouping of icons within an icon library
some libraries don’t sub-divide the icons - so the category is the library
Icon Each category consists one or more icons
An Icon is a decorated sprite e.g. a coloured sprite in a rectangle with all the text and colour
Macro The pre-processor code applied to a sprite
i.e. the define/definelong or function/procedure associated with a sprite to make it an icon
The call from the user puml file is a macro.
Sprite A 2D bitmap
Diagram Everything you see. Everything represented by the puml file
Style A collection of attributes that specify the appearance for a single icon.
A style can specify attributes such as font color, font size, background color, and much more.
Optional.
If present, takes precedence over a theme
Theme A type of style that's applied to the entire diagram - not just an individual icon.
A collection of coordinated styles that determine the color, background attributes, and the fonts used on a layout.
Themes also enhance the appearance of a layout and give all your layouts a consistent look.
A theme does not control the placement or behavior of fields or objects on a layout.
Layout An arrangement of fields, objects, pictures, and layout parts that represents the way information is organized and presented.

Do we need individual sprite files? e.g. awslib/ARVR/Sumerian.puml and associated png (or svg), as all info is in puml file

Plantuml Stdlib File Layout

Standardising Sprites

Property Value
XxY 128x128
Sprite resolution SHOULD be this value or close to it.
Current sprite libraries range from ~40 to 256.
Levels 16
Sprite resolution SHOULD be this value.
4, 8, 16 are the possible options.

ref: https://tools.ietf.org/html/rfc2119 for SHOULD, MUST, MAY meaning

Standardising Icon Macro API

Mode Details
Standard Keyword arguments SHOULD be used for all parameters per todo ref

This gives future proofing: as new parameters are added over time,
user specifies only the parameter they care about
for the parameter they care about, only named keyword arguments are used
Legacy To work with a subset of existing user diagrams, new macros will enforce the parameter ordering per Type 2

e.g. !define AzureBatchAI(e_alias, e_label, e_techn, e_descr) AzureEntity(e_alias, e_label, e_techn, e_descr, AZURE_SYMBOL_COLOR, AzureBatchAI, AzureBatchAI)

Existing macros in existing libraries should be kept, even when a newer keywords arguments mode is added
This ensures backwards compatibility of PlantUML Stdlib with existing user diagrams.
Mixed This mix of ordered parameters, with keyword parameters is also possible.

This is not as future proof as Standard mode.

Mode Example

#Legacy
#ordering does matter
ExistingMacro("alias", "label", "techn", "descr")

#Standard
#keyword arguments for all parameters
#ordering does NOT matter
NewMacro(alias="myalias", label="mylabel", techn="mytechn", descr="mydescr", newParam1="whatever", newParam2=3)
NewMacro(techn="mytechn", alias="myalias", descr="mydescr", newParam1="whatever", label="mylabel", newParam2=3)

#Mixed
#if we don't use keyword arguments then same as ExistingMacro
#ordering does matter
NewMacro("alias", "label", "techn", "descr")

#ordering does matter for existing parameters only
NewMacro("alias", "label", "techn", "descr", newParam1="whatever", newParam2=3)

Mode Demo

Main features

The demo uses most of the available Preprocessor features (https://plantuml.com/preprocessing)

  1. User specifies only the parameters they care about. Preprocessor "Keywords arguments" used.

  2. If user does not specify the parameter, then the default value is used. Preprocessor "Default argument value" used.

  3. `rectangle $alias <<$alias>> is in form shape alias <<stereo>>` where skinparam can be specified for a stereo per https://plantuml.com/skinparam last example

  4. Dynamic invocation to somewhat decouple the sprite, parameters, and layout. Not as decoupled as I'd like as still need to pass all params for each sprite at definition time.

  5. https://plantuml.com/preprocessing Conditions to show

    1. technology "[ ]" only if technology specified.
    2. focus hi/lo/normal based on parameter which changes skinparams for the stereo (where alias is used as stereo)

  6. '""== $labeln": "==" is creole syntax for "Large heading" (https://plantuml.com/creole)

  7. icon fields are laid out line-by-line for clarity

  8. parameters supported are

    1. $MySprite,
    2. $alias,
    3. $description="",
    4. $label="",
    5. $technology="",
    6. $scale=1,
    7. $colour="blue",
    8. $shape="cloud",
    9. $textsize="18",
    10. $focus=""

In the full demo, the sprite decorator is selected by user via e.g. '!includeurl AWSPuml/SpriteDecorators.iuml!SPRITEDECORATOR_3. This uses the "File List.iuml" block include Preprocessor feature

Full code applied to PlantUML Stdlib is in https://github.com/Crashedmind/plantuml-stdlib2.0/commit/2a9b1f2621bc81c1f0dd0ec366c028fe60032dc0

Below is a standalone file version of it.

@startuml
'all sprites in a category would be included in an all.puml file for that category
'==================================================================================================


' Styling
' ##################################

!define TECHN_FONT_SIZE 12

skinparam defaultTextAlignment center

skinparam wrapWidth 200
skinparam maxMessageSize 150

skinparam rectangle {
    StereotypeFontSize 12
}


skinparam rectangle {
backgroundColor white
}
skinparam cloud {
backgroundColor white
}


!define LAYOUT_TOP_DOWN top to bottom direction
!define LAYOUT_LEFT_RIGHT left to right direction



sprite $Analytics [64x64/16z] {
xTK5WiGW38NXbn1WGkv_tjMwDwml__YqNrtmNRK8tISXfBj5W4UVhDpBTExBtVweRxvv5TfCz9eNnCqWrpo9bOrCwAelc_bzJYdNU0QWvlTAe0glJ14-tt7L
w5d_h6yBJ-hR_W9wMCSTNf0OiUFtVCUj23f-smjojmbSNiR_7BwRkz-dN7l-k7pz-IyXWC9cX13ap3CuxCRWCwyGsqsWPxvaIDn9a2zilqYxnJzv_sg-UQlp
KU_sc7b77-V1mHEFioLN-0iz0m
}

!unquoted procedure $ANALYTICS ($alias, $description="", $label="", $technology="", $scale=1, $colour="693CC5", $shape="rectangle", $textsize="12", $focus="")
%invoke_procedure($SpriteDecorator, "$Analytics", $alias, $description, $label, $technology, $scale, $colour, $shape, $textsize, $focus)
!endprocedure


sprite $AppSync [64x64/16z] {
xPRdrkCW34IlGAYmx_-yMr89PwtZBxzzquF6rWoupFznSN6HuVONZ_n6x5ru8DtpX-eX85tjBze5PEGyZmcevxiNXJY_SmNTTXT-NjveHVK9US_vFGsTXqJa
h55w8GVfmuie7SbLCCPQRDp9G_F26jq066jpYBiU6pJMiK3CX5YpOSm2uRFTSNzxaBH4idBVvwuVs3ByIx4gVD_IqB6iN1URGQ_Qpsrxi2QIVuVbs43Izjcu
vxVIYMFxEbVqvdzhU6m1R7ajn3rhmOkY5VlSTBl_z4zNVbPlJrt7JkhVGp5KY9SF7R4LrVaPG7iR0MpBhvg_5CmRbZUCvWQvp5-nVZBotaZmmfUbAMIvVXsz
Br97sWt1vkntVRr-dNxtr-W3_9aVsf_7dMBryNlp5mtUXGQqk-lakFt8QNIHMvtxgsxzDHZ5kQifeFEOe3Zwj06K_bevEjErIPmukHTa9PUStwD8VA-EHZil
zwqq1p-vh2RqxVv1R9udJO2czfTHtB-KKxdSFzbNkTVtRnSN5ty
}

!unquoted procedure $APPSYNC ($alias, $description="", $label="", $technology="", $scale=1, $colour="CC2264", $shape="rectangle", $textsize="12", $focus="")

%invoke_procedure($SpriteDecorator, "$AppSync", $alias, $description, $label, $technology, $scale, $colour, $shape, $textsize, $focus)

!endprocedure

sprite $ApplicationIntegration [64x64/16z] {
xTO5GiOm30NWbwIIXFlVbxL8AROrmzdxPVfDQ_YkNA67AK7AQZB0mvSRNupDtdikVtahxyHslH5eAkBJ4jcUBr0RSH6t4KNPzMG-qloJ6Erx36zLUVPOyPK0
nBr2L2M5VQ8-5_ViST_dgdkjOMyC4KYRrPoAhNgtp4pDLu31jkP7-J7Qh295lQBsrt7Caxyu_wDtslUG5dLBRKea8kZNZpPtm3CBi7d6WvUqUMavUFsK-bEt
kVuTl7vxzDfyfFoaVlsqpGddL9UzSTlOdBIjQTMxbPIrB-QsggxwEPI-pPTidazSlm24x77FEQj7VQJyKDp7-wzu_tc-_xx6FvVFjXgTV20Vvy4I2O_JKYZu
2xa5
}

!unquoted procedure $APPLICATIONINTEGRATION ($alias, $description="", $label="", $technology="", $scale=1, $colour="CC2264", $shape="rectangle", $textsize="12", $focus="")

%invoke_procedure($SpriteDecorator, "$ApplicationIntegration", $alias, $description, $label, $technology, $scale, $colour, $shape, $textsize, $focus)

!endprocedure




'=============================DECORATORS==================================
' We define 1 or more sprite decorators in stdlib
' Define our decorators that we know now - and can easily define new ones in future with as manty new parameters 
' as we want, that we don't even know about yet
' Let's say SpriteDecorator is defined month 1, SpriteDecorator2 is defined month 2, SpriteDecorator3 is defined month 3
'
' https://plantuml.com/preprocessing Conditions to show technology "[ ]" only if technology specified
'""== $label\n": "==" is creole syntax for "Large heading" https://plantuml.com/creole
' rectangle $alias <<$alias>> is in form "shape alias <<stereo>>" where skinparam can be specified for a stereo per https://plantuml.com/skinparam last example
' https://plantuml.com/preprocessing Conditions to show technology "[ ]" only if technology specified
' https://plantuml-documentation.readthedocs.io/en/latest/formatting/all-skin-params.html for all skinparams
'---------------------------------------------------



'add a new shape parameter + a textsize parameter
'---------------------------------------------------
!unquoted procedure $SpriteDecorator($MySprite, $alias, $description="", $label="", $technology="", $scale=1, $colour="blue", $shape="cloud", $textsize="18", $focus="" )

!if ($focus == "hi")
    skinparam rectangle {
        backgroundColor<<$alias>> yellow
        borderColor<<$alias>> yellow
        shadowing<<$alias>> true
        BorderThickness<<$alias>> 20
    }
!endif

!if  ($focus == "lo")
    skinparam rectangle {
        backgroundColor<<$alias>> gainsboro
        borderColor<<$alias>> gainsboro
        shadowing<<$alias>> false
        
    }
!endif


!if ($technology == "")
    $shape $alias <<$alias>> as "
    == $label\n
    <color:$colour><$MySprite*$scale></color>

    $description "
!else 
    $shape $alias <<$alias>> as "
    == $label\n
    <color:$colour><$MySprite*$scale></color>
    //<size:$textsize>[$technology]</size>//

    $description "
!endif

!endprocedure


!$SpriteDecorator = "$Sprite"+ "Decorator"
'=============================END DECORATORS==================================

LAYOUT_LEFT_RIGHT

' User can specify what they want in order (legacy mode), or via named arugments (standard mode)
package modes {
'legacy mode
$ANALYTICS("legacy1", "description", "label", "technology", 1)
$ANALYTICS("legacy2", "desc", "label", "tech", 2, "brown")

'mixed mode
$ANALYTICS("mixed", $shape="cloud")
'standard mode
$APPSYNC($alias="standard", $description="description", $label="label")
}

package scale {
$ANALYTICS($alias="x0.5", $scale="0.5")
$ANALYTICS($alias="x1" )
$ANALYTICS($alias="x1.5", $scale="1.5")
'NOTE: if we use 1.5 instead of "1.5" then it's interpreted as .5 i.e. wrong

x0.5 -->x1
x1--> x1.5
}

'standard mode
package focus {
$APPSYNC($alias="lofocus", $description="description", $label="lo focus", $technology="technology", $focus="lo")
$APPSYNC($alias="normal", $description="description", $label="normal", $technology="technology")
$APPSYNC($alias="hifocus", $description="description", $label="hi focus", $technology="technology", $focus="hi")

lofocus -->normal
normal--> hifocus
}



footer %filename() rendered with PlantUML version %version()\nThe Hitchhiker’s Guide to PlantUML

@enduml
On this page

  1. Standardising Standard Library
    1. Plantuml Stdlib Terminology
    2. Plantuml Stdlib File Layout
    3. Standardising Sprites
    4. Standardising Icon Macro API
    5. Mode Example
    6. Mode Demo
      1. Main features

Brodocs